Listbox in Dialog
Volume Number: 1
Issue Number: 7
Column Tag: C workshop
Listbox in a Dialog
By Robert B. Denny
I have often wanted to have the ability to put up a dialog box like that of “Standard
File”, where the user could select from a list of strings.
Implementing such a function requires a combination of most of the Macintosh
technology we have covered in the past several months, plus the services of the Dialog
Manager. And not just the usual dialog services, we’ll need to implement a filter
function to manage the selection box and scroll bar(s) within the dialog.
This month’s C Workshop makes up for past columns which showed relatively
few C programming examples. Instead of explaining the theory of using the dialog
manager and it’s filter function hooks, I am instead submitting a complete C function
that can be used with most compilers which implements a single- selection dialog
similar to that of Standard File.
The appearance of the dialog is completely controlled by resource data, including
the dimensions of the selection box. Scroll bars are provided in both vertical and
horizontal axes, and automatically size to the selection box dimensions. This particular
example was used in a utility to perform name lookups on AppleTalk using the Name
Binding Protocol (NBP), and allow selection of a particular object by name.
To use the function sel_ dialog(), call it with 3 arguments: a “call-back”
function name (explained below) and the address and size of a buffer to receive a copy
of the selected string. Four buttons control its operation.
“Lookup” causes the “call-back” function to be called repeatedly for pointers to
P-strings to put into the selection window. This action continues until the call-back
function returns NULL. The strings do not have to be kept around after being passed to
sel_ dialog(), they are stored in the TERec’s linear text array. The Lookup button may
be pressed repeatedly for many fill-in cycles.
If any of the strings are too long to fit in the selection box horizontally, the
horizontal scroller is turned on and ranged for the longest string. It con- tinues to be
ranged for the longest string as additional strings are added there- after. Likewise, the
vertical scroller is turned on and continually ranged if there are more strings than
will fit vertically in the selection box.
After a lookup cycle, the strings in the selector box are armed for mouse clicks
and are highlighted when clicked. If any strings are highlighted, the “Accept” button
is turned on.
Pressing “Accept” causes the selected string to be copied into the buffer supplied
as an argument. “Cancel” causes sel_ dialog() to return with a null string in the
caller’s buffer. In either case the dialog and all associated data in memory is released
and a return to the caller is made.
“Clear” causes the selector box to be cleared; all strings are erased and the
scrollers are reset and turned off. This might be useful in preparation for a new
lookup process.
Resources Control Appearance
Sel_ dialog() is written to be controlled by a set of resources which completely
determine the dialog’s layout, including the location and titles of the buttons and the
location and dimensions of the selection window. The example here is very similar to
the dialog used by Standard File, but it needn’t be. Just observe the correlation
between the buttons’ DITL item numbers and their functions. Obviously, you can
change the code to eliminate buttons, but you can do so as well by “placing” the buttons
off- screen without loss of generality of the function.
Here is the RMAKER source for the example shown on the next pages, followed by
some pictures of the dialog and the code for sel_ dialog(). Note the homebrew ‘RECT’
resource which sets the location and dimensions of the selection box.
TYPE DLOG
,256
72 72 224 420
Invisible NoGoAway
1
0
256
TYPE DITL
,256
7
button
28 152 46 232
Accept
button
90 152 108 232
Cancel
button
59 256 77 336
Lookup
button
90 256 108 336
Clear
staticText Disabled
28 254 46 344
NBP Lookup
*Selector box Rect
TYPE RECT = GNRL
,256
.I
11 12 125 125
By any measure, this is an “advanced” programming example. Little explanation
accompanies the code. I highly recommend you review the Dialog Manager section of
Inside Macintosh before working through this example. Note how the filter function and
modal dialog loops interact to provide the user interface with just a simple function
call from the client application.
The dialog box looks like this when it first appears:
If the “Lookup” button is pressed, your routine gets called repeatedly for
P-strings to be inserted in the list shown in the window, until it returns NULL. If one
of the strings is longer than will fit in the window, the horizontal scroller will be
turned on and ranged appropriately, like this:
If your routine returns enough strings to fill up the window vertically, the
vertical scroller will be turned on, like this:
After your call-back function has finished, the mouse becomes active and may be
used to push buttons and select text. If you click in one of the items in the select
window, it will be highlighted and the “Accept” button will be activated like this:
The C code which makes up the rest of this article implements this general
purpose selection dialog. Macintosh toolbox calls are italicized for emphasis. The
assembly routines use the linkage conventions of Consulair Mac C, and will need minor
changes for other C implementations. Other than these differences, the code below
should be easy to use under any of the C systems available for the Mac. There are no
“library” routines used at all, except those in the Macintosh ROM.
/* Resource IDs */
#define DLOG_ID 256 /* Dialog window itself */
#define BOX_ID 256 /* Selector box Rectangle */
/* DITL item numbers , also part codes */
#define ACCEPT 1 /* The Accept button */
#define CANCEL 2 /* The Cancel button */
#define LOOKUP 3 /* The Lookup button */
#define CLEAR 4 /* The Clear button */
#define TITLE 5 /* static title (NBP Lookup) */
/* Local static variables */
static Rect box_rect; /* Box rect (from resource) */
static ControlHandle v_scroll; /* ->-> V-Scroller */
static ControlHandle h_scroll; /* ->-> H-Scroller */
static ControlHandle acc_ button; /* ->-> Accept button */
static Rect dest_rect; /* TextEdit’s destination rect */
static Rect view_rect; /* Text Edit’s view Rect */
static short int vs_offs; /* destRect vertical offset */
static short int hs_offs; /* destRect horiz offset */
static TEHandle hTE; /* Handle to TextEdit record */
static unsigned short line_height; /* Text line height, pixels */
static unsigned short lines_vis; /* No. of whole lines visible */
static unsigned short half_wid; /* half width of box in pixels */
static Point loc_pt; /* Local coord of last mouse click */
/*
* SEL_DIALOG() - MAIN DIALOG FUNCTION
*
* Inputs:
* P1 procedure to call to add an item. Returns pointer to
* P-string to add to the items in the box (no newline);
* Must return NULL when no more to add.
* P2 address of buffer to receive selection
* P3 length (bytes) of selection buffer
*
* Outputs:
* If Accept pressed, selected string is copied as a
* C-string into the P2 buffer, up to P3-1 bytes. If Cancel
* pressed, a null C-string is placed into the P2 buffer
*/
sel_ dialog(add_item, sel_buf, buf_len)
char *(*add_item)(); /* User call-back to add item */
char *sel_buf; /* Buffer to receive selection */
short buf_len; /* Length of buffer to receive selection */
{
Ptr dp; /* Dialog pointer */
Rect **rh; /* Handle to resource rect */
Rect scr_rect; /* Scratch rect */
long il; /* Length of text from user */
char *cp; /* Ptr for scanning user items */
short scratch; /* Scratch word */
unsigned short item_hit; /* Item number hit in dialog */
unsigned short done; /* Flag indicating he’s done */
unsigned short sw; /* String width, pixels */
unsigned short cv; /* Control value buffer */
unsigned short max_wid; /* Max line width pixels */
unsigned short sel_line; /* Line number of selected line */
unsigned short sel_start; /* Index of 1st char of sel line */
unsigned short sel_end; /* Index 1st char after sel line */
unsigned short sel_len; /* Length of selected text */
short hce, vce; /* Flags TRUE if scroller enabled */
int user_Filt(); /* Dialog filter */
dp = (Ptr)GetNewDialog (DLOG_ID, 0, -1); /* Load dialog */
SetPort (dp); ‘ /* Hook QuickDraw to dialog */
/*
* Dim the accept button & save it’s handle for later
* Disable it until something is selected
*/
GetDItem (dp, ACCEPT, &scratch, &acc_ button, &scr_rect);
HiliteControl (acc_ button, 255);
/* “part” 255 means dim & disable */
/*
* Get the box rect as a resource & copy it
locally, then release it
*/
rh = (Rect *)GetResource (‘RECT’, BOX_ID); /* Get rect*/
box_rect.topLeft.all = (*rh)->topLeft.all;
box_rect.botRight.all = (*rh)->botRight.all;
ReleaseResource (rh); /* No need for this now */
/*
* Put up the scroll bars. Compute their sizes from the
selector box rectangle.
*/
scr_rect.top = box_rect.top; /* Vert scroll bar on right edge */
scr_rect.left = box_rect.right - 1; /* Overlap wind box 1 pix */
scr_rect.bottom = box_rect.bottom;
scr_rect.right = scr_rect.left + 16; /* Standard 16-pix width */
v_scroll = (ControlHandle)NewControl (dp, &scr_rect, 0, TRUE, 0,
0, 0, scrollBarProc, 0);
HiliteControl (v_scroll, 255); /* Deactivate for now */
vce = FALSE;
scr_rect.top = box_rect.bottom - 1; /* Horiz. scroll bar */
scr_rect.left = box_rect.left; /* Same overlap, width */
scr_rect.bottom = scr_rect.top + 16;
scr_rect.right = box_rect.right;
h_scroll = (ControlHandle)NewControl (dp, &scr_rect, 0, TRUE, 0,
0, 0, scrollBarProc, 0);
HiliteControl (h_scroll, 255); /* Deactivate for now */
hce = FALSE;
/*
* Set up a TextEdit record for the items in the box. Leave 3
pixel bleed on left, none on the
* right, 3 at the top of the destRect. Must never wrap or go
off bottom. Calculate the number
* of complete lines of text visible in the view_rect.
*/
dest_rect.top = box_rect.top + 3;
dest_rect.left = box_rect.left + 3;
dest_rect.right = 1000; /* room for long text items */
dest_rect.bottom = 2000;